Extract and dynamically re-inject base client sphinx param doc into client classes, for better sphinx and runtime doc #1131
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Add three helpers to
utils
in order to improve the runtimedocstrings for client classes.
read_sphinx_params
-- a simple:param:
parserinject_sphinx_params
-- a__doc__
rewriter which takes parsedparams and inserts them in place of a special marker comment
inject_sphinx_params_of
-- a decorator version of these whichchains together reading the docstring of one object and
modifying the docstring of another
Then apply these to write
and so forth. This is applied to all client classes except for the
Auth login clients, which do not inherit all of the parameters of
BaseClient
-- in particular, we do not allow construction of alogin client with an
app
.read_sphinx_params
gets a functools cache, but the rest of the workis still done dynamically, so there is a little bit of repetition.
This results in improved docstrings for sphinx and for runtime usages
like
help(globus_sdk.TransferClient)
. Static analyzers (e.g., IDEs)will pick up on the original source string, which will show the marker
comment used to drive this behavior:
📚 Documentation preview 📚: https://globus-sdk-python--1131.org.readthedocs.build/en/1131/